<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <meta name="author" content="PG-Strom Development Team">
  <link rel="shortcut icon" href="../img/favicon.ico">
  <title>GUC Parameters - PG-Strom Manual</title>
  <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>

  <link rel="stylesheet" href="../css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
  <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css">
  <link href="//fonts.googleapis.com/earlyaccess/notosansjp.css" rel="stylesheet">
  <link href="//fonts.googleapis.com/css?family=Open+Sans:600,800" rel="stylesheet">
  <link href="../custom.css" rel="stylesheet">
  
  <script>
    // Current page data
    var mkdocs_page_name = "GUC Parameters";
    var mkdocs_page_input_path = "ref_params.md";
    var mkdocs_page_url = null;
  </script>
  
  <script src="../js/jquery-2.1.1.min.js" defer></script>
  <script src="../js/modernizr-2.8.3.min.js" defer></script>
  <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
  <script>hljs.initHighlightingOnLoad();</script> 
  
</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
      <div class="wy-side-nav-search">
        <a href=".." class="icon icon-home"> PG-Strom Manual</a>
        <div role="search">
  <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
  </form>
  [<a href="../ja/ref_params/" style="color: #cccccc">Japanese</a> | <strong>English</strong>]
</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
	<ul class="current">
	  
          
            <li class="toctree-l1">
		
    <a class="" href="..">Home</a>
	    </li>
          
            <li class="toctree-l1">
		
    <a class="" href="../install/">Install</a>
	    </li>
          
            <li class="toctree-l1">
		
    <span class="caption-text">Tutorial</span>
    <ul class="subnav">
                <li class="">
                    
    <a class="" href="../operations/">Basic Operations</a>
                </li>
                <li class="">
                    
    <a class="" href="../sys_admin/">System Administration</a>
                </li>
                <li class="">
                    
    <a class="" href="../brin/">BRIN Index</a>
                </li>
                <li class="">
                    
    <a class="" href="../partition/">Partitioning</a>
                </li>
                <li class="">
                    
    <a class="" href="../postgis/">PostGIS</a>
                </li>
                <li class="">
                    
    <a class="" href="../troubles/">Trouble Shooting</a>
                </li>
    </ul>
	    </li>
          
            <li class="toctree-l1">
		
    <span class="caption-text">Advanced Features</span>
    <ul class="subnav">
                <li class="">
                    
    <a class="" href="../ssd2gpu/">GPUDirect SQL</a>
                </li>
                <li class="">
                    
    <a class="" href="../arrow_fdw/">Apache Arrow</a>
                </li>
                <li class="">
                    
    <a class="" href="../gstore_fdw/">GPU Memory Store</a>
                </li>
                <li class="">
                    
    <a class="" href="../python/">Python cooperation</a>
                </li>
    </ul>
	    </li>
          
            <li class="toctree-l1">
		
    <span class="caption-text">References</span>
    <ul class="subnav">
                <li class="">
                    
    <a class="" href="../ref_types/">Data Types</a>
                </li>
                <li class="">
                    
    <a class="" href="../ref_devfuncs/">Functions and Operators</a>
                </li>
                <li class="">
                    
    <a class="" href="../ref_sqlfuncs/">SQL Objects</a>
                </li>
                <li class=" current">
                    
    <a class="current" href="./">GUC Parameters</a>
    <ul class="subnav">
            
    <li class="toctree-l3"><a href="#enablesdisables-a-particular-feature">Enables/disables a particular feature</a></li>
    

    <li class="toctree-l3"><a href="#optimizer-configuration">Optimizer Configuration</a></li>
    

    <li class="toctree-l3"><a href="#executor-configuration">Executor Configuration</a></li>
    

    <li class="toctree-l3"><a href="#gpudirect-sql-configuration">GPUDirect SQL Configuration</a></li>
    

    <li class="toctree-l3"><a href="#arrow_fdw-configuration">Arrow_Fdw Configuration</a></li>
    

    <li class="toctree-l3"><a href="#gstore_fdw-configuration">Gstore_Fdw Configuration</a></li>
    

    <li class="toctree-l3"><a href="#configuration-of-gpu-code-generation-and-build">Configuration of GPU code generation and build</a></li>
    

    <li class="toctree-l3"><a href="#gpu-device-configuration">GPU Device Configuration</a></li>
    

    <li class="toctree-l3"><a href="#system-shared-memory-configuration">System Shared Memory Configuration</a></li>
    

    </ul>
                </li>
    </ul>
	    </li>
          
            <li class="toctree-l1">
		
    <a class="" href="../release_note/">Release Note</a>
	    </li>
          
        </ul>
      </div>
      &nbsp;
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="..">PG-Strom Manual</a>
      </nav>

      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="..">Docs</a> &raquo;</li>
    
      
        
          <li>References &raquo;</li>
        
      
    
    <li>GUC Parameters</li>
    <li class="wy-breadcrumbs-aside">
      
    </li>
  </ul>
  <hr/>
</div>
          <div role="main">
            <div class="section">
              
                <h1>GUC Parameters</h1>

<p>This session introduces PG-Strom's configuration parameters.</p>
<h1 id="enablesdisables-a-particular-feature">Enables/disables a particular feature</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>pg_strom.enabled</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables entire PG-Strom features at once</td>
</tr>
<tr>
<td align="left"><code>pg_strom.enable_gpuscan</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables GpuScan</td>
</tr>
<tr>
<td align="left"><code>pg_strom.enable_gpuhashjoin</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables GpuJoin by HashJoin</td>
</tr>
<tr>
<td align="left"><code>pg_strom.enable_gpunestloop</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables GpuJoin by NestLoop</td>
</tr>
<tr>
<td align="left"><code>pg_strom.enable_gpupreagg</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables GpuPreAgg</td>
</tr>
<tr>
<td align="left"><code>pg_strom.enable_brin</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables BRIN index support on tables scan</td>
</tr>
<tr>
<td align="left"><code>pg_strom.enable_partitionwise_gpujoin</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables whether GpuJoin is pushed down to the partition children. Available only PostgreSQL v10 or later.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.enable_partitionwise_gpupreagg</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables whether GpuPreAgg is pushed down to the partition children. Available only PostgreSQL v10 or later.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.pullup_outer_scan</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables to pull up full-table scan if it is just below GpuPreAgg/GpuJoin, to reduce data transfer between CPU/RAM and GPU.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.pullup_outer_join</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables to pull up tables-join if GpuJoin is just below GpuPreAgg, to reduce data transfer between CPU/RAM and GPU.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.enable_numeric_aggfuncs</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables support of aggregate function that takes <code>numeric</code> data type.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.cpu_fallback</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>off</code></td>
<td align="left">Controls whether it actually run CPU fallback operations, if GPU program returned "CPU ReCheck Error"</td>
</tr>
<tr>
<td align="left"><code>pg_strom.regression_test_mode</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>off</code></td>
<td align="left">It disables some <code>EXPLAIN</code> command output that depends on software execution platform, like GPU model name. It avoid "false-positive" on the regression test, so use usually don't tough this configuration.</td>
</tr>
</tbody>
</table>
<h1 id="optimizer-configuration">Optimizer Configuration</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>pg_strom.chunk_size</code></td>
<td align="center"><code>int</code></td>
<td align="center">65534kB</td>
<td align="left">Size of the data blocks processed by a single GPU kernel invocation. It was configurable, but makes less sense, so fixed to about 64MB in the current version.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.gpu_setup_cost</code></td>
<td align="center"><code>real</code></td>
<td align="center">4000</td>
<td align="left">Cost value for initialization of GPU device</td>
</tr>
<tr>
<td align="left"><code>pg_strom.gpu_dma_cost</code></td>
<td align="center"><code>real</code></td>
<td align="center">10</td>
<td align="left">Cost value for DMA transfer over PCIe bus per data-chunk (64MB)</td>
</tr>
<tr>
<td align="left"><code>pg_strom.gpu_operator_cost</code></td>
<td align="center"><code>real</code></td>
<td align="center">0.00015</td>
<td align="left">Cost value to process an expression formula on GPU. If larger value than <code>cpu_operator_cost</code> is configured, no chance to choose PG-Strom towards any size of tables</td>
</tr>
</tbody>
</table>
<h1 id="executor-configuration">Executor Configuration</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>pg_strom.max_async_tasks</code></td>
<td align="center"><code>int</code></td>
<td align="center"><code>5</code></td>
<td align="left">Number of asynchronous taks PG-Strom can throw into GPU's execution queue per process. If CPU parallel is used in combination, this limitation shall be applied for each background worker. So, more than <code>pg_strom.max_async_tasks</code> asynchronous tasks are executed in parallel on the entire batch job.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.reuse_cuda_context</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>off</code></td>
<td align="left">If <code>on</code>, it tries to reuse CUDA context, constructed according to the previous query execution, on the next query execution. Usually, construction of CUDA context takes 100-200ms, it may improve queries response time, on the other hands, it continue to occupy a part of GPU device memory on the down-side. So, we don't recommend to enable this parameter expect for benchmarking and so on.<br>Also, this configuration makes no sense if query uses CPU parallel execution.</td>
</tr>
</tbody>
</table>
<h1 id="gpudirect-sql-configuration">GPUDirect SQL Configuration</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>pg_strom.gpudirect_driver</code></td>
<td align="center"><code>text</code></td>
<td align="center">auto</td>
<td align="left">It shows the driver software name of GPUDirect SQL (read-only).</td>
</tr>
<tr>
<td align="left"><code>pg_strom.gpudirect_enabled</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Enables/disables GPUDirect SQL feature.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.gpudirect_threshold</code></td>
<td align="center"><code>int</code></td>
<td align="center">auto</td>
<td align="left">Controls the table-size threshold to invoke GPUDirect SQL feature.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.cufile_io_unitsz</code></td>
<td align="center"><code>int</code></td>
<td align="center"><code>16MB</code></td>
<td align="left">Unit size of read-i/o when PG-Strom uses cuFile API. No need to change from the default setting for most cases. It is available only if PG-Strom was built with <code>WITH_CUFILE=1</code>.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.nvme_distance_map</code></td>
<td align="center"><code>string</code></td>
<td align="center"><code>NULL</code></td>
<td align="left">It manually configures the closest GPU for particular NVME devices. Its format string is <code>&lt;nvmeX&gt;:&lt;gpuX&gt;[,...]</code>; comma separated list of NVME-GPU pairs. (Examle: <code>nvme0:gpu0,nvme1:gpu0</code>)<br>Automatic configuration is often sufficient for local NVME-SSD drives, on the other hands, you need to configure the closest GPU manually, if NVME-oF devices are in use.</td>
</tr>
</tbody>
</table>
<h1 id="arrow_fdw-configuration">Arrow_Fdw Configuration</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>arrow_fdw.enabled</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">By adjustment of estimated cost value, it turns on/off Arrow_Fdw. Note that only Foreign Scan (Arrow_Fdw) can scan on Arrow files, if GpuScan is not capable to run on.</td>
</tr>
<tr>
<td align="left"><code>arrow_fdw.metadata_cache_size</code></td>
<td align="center"><code>int</code></td>
<td align="center">128MB</td>
<td align="left">Size of shared memory to cache metadata of Arrow files.<br>Once consumption of the shared memory exceeds this value, the older metadata shall be released based on LRU.</td>
</tr>
<tr>
<td align="left"><code>arrow_fdw.record_batch_size</code></td>
<td align="center"><code>int</code></td>
<td align="center">256MB</td>
<td align="left">Threshold of RecordBatch when Arrow_Fdw foreign table is written. When total amount of the buffer size exceeds this configuration, Arrow_Fdw writes out the buffer to Apache Arrow file, even if <code>INSERT</code> command is not completed yet.</td>
</tr>
</tbody>
</table>
<h1 id="gstore_fdw-configuration">Gstore_Fdw Configuration</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>gstore_fdw.enabled</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">By adjustment of estimated cost value, it turns on/off Gstore_Fdw. Note that only Foreign Scan (Gstore_Fdw) can scan on GPU memory store, if GpuScan is not capable to run on.</td>
</tr>
<tr>
<td align="left"><code>gstore_fdw.auto_preload</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>on</code></td>
<td align="left">Controls whether the GPU memory store shall be pre-loaded to GPU devices next to the PostgreSQL startup. If not pre-loaded, GPU memory store shall be loaded on the demand by someone's reference. It may lead slow-down of query response time on the first call.</td>
</tr>
<tr>
<td align="left"><code>gstore_fdw.default_base_dir</code></td>
<td align="center"><code>text</code></td>
<td align="center"><code>NULL</code></td>
<td align="left">Directory to create base files, if <code>base_file</code> was not specified in the foreign-table options. In the default, it shall be created on the default tablespace of the current database.</td>
</tr>
<tr>
<td align="left"><code>gstore_fdw.default_redo_dir</code></td>
<td align="center"><code>text</code></td>
<td align="center"><code>NULL</code></td>
<td align="left">Directory to create redo-log files, if <code>redo_log_file</code> was not specified in the foreign-table options. In the default, it shall be created on the default tablespace of the current database.</td>
</tr>
</tbody>
</table>
<h1 id="configuration-of-gpu-code-generation-and-build">Configuration of GPU code generation and build</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>pg_strom.program_cache_size</code></td>
<td align="center"><code>int</code></td>
<td align="center"><code>256MB</code></td>
<td align="left">Amount of the shared memory size to cache GPU programs already built. It needs restart to update the parameter.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.num_program_builders</code></td>
<td align="center"><code>int</code></td>
<td align="center"><code>2</code></td>
<td align="left">Number of background workers to build GPU programs asynchronously. It needs restart to update the parameter.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.debug_jit_compile_options</code></td>
<td align="center"><code>bool</code></td>
<td align="center"><code>off</code></td>
<td align="left">Controls to include debug option (line-numbers and symbol information) on JIT compile of GPU programs. It is valuable for complicated bug analysis using GPU core dump, however, should not be enabled on daily use because of performance degradation.</td>
</tr>
<tr>
<td align="left"><code>pg_strom.extra_kernel_stack_size</code></td>
<td align="center"><code>int</code></td>
<td align="center"><code>0</code></td>
<td align="left">Extra size of stack, in bytes, for each GPU kernel thread to be allocated on execution. Usually, no need to change from the default value.</td>
</tr>
</tbody>
</table>
<h1 id="gpu-device-configuration">GPU Device Configuration</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>pg_strom.cuda_visible_devices</code></td>
<td align="center"><code>string</code></td>
<td align="center"><code>''</code></td>
<td align="left">List of GPU device numbers in comma separated, if you want to recognize particular GPUs on PostgreSQL startup. It is equivalent to the environment variable <code>CUDAVISIBLE_DEVICES</code></td>
</tr>
<tr>
<td align="left"><code>pg_strom.gpu_memory_segment_size</code></td>
<td align="center"><code>int</code></td>
<td align="center"><code>512MB</code></td>
<td align="left">Specifies the amount of device memory to be allocated per CUDA API call. Larger configuration will reduce the overhead of API calls, but not efficient usage of device memory.</td>
</tr>
</tbody>
</table>
<h1 id="system-shared-memory-configuration">System Shared Memory Configuration</h1>
<table>
<thead>
<tr>
<th align="left">Parameter</th>
<th align="center">Type</th>
<th align="center">Default</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">shmbuf.segment_size</td>
<td align="center"><code>int</code></td>
<td align="center"><code>256MB</code></td>
<td align="left"></td>
</tr>
<tr>
<td align="left">shmbuf.num_logical_segments</td>
<td align="center"><code>int</code></td>
<td align="center">auto</td>
<td align="left">Default logical segment size is double size of system physical memory size.</td>
</tr>
</tbody>
</table>
              
            </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="../release_note/" class="btn btn-neutral float-right" title="Release Note">Next <span class="icon icon-circle-arrow-right"></span></a>
      
      
        <a href="../ref_sqlfuncs/" class="btn btn-neutral" title="SQL Objects"><span class="icon icon-circle-arrow-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <!-- Copyright etc -->
    
  </div>

  Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
      
        </div>
      </div>

    </section>

  </div>

  <div class="rst-versions" role="note" style="cursor: pointer">
    <span class="rst-current-version" data-toggle="rst-current-version">
      
      
        <span><a href="../ref_sqlfuncs/" style="color: #fcfcfc;">&laquo; Previous</a></span>
      
      
        <span style="margin-left: 15px"><a href="../release_note/" style="color: #fcfcfc">Next &raquo;</a></span>
      
    </span>
</div>
    <script>var base_url = '..';</script>
    <script src="../js/theme.js" defer></script>
      <script src="../search/main.js" defer></script>

</body>
</html>
